Inside Macintosh: QuickTime Components

| Previous | Chapter contents | Chapter top | Section top | Next |

Importing Movie Data

Movie data import components may provide one or two functions that allow the Movie Toolbox to request a data conversion operation. The MovieImportHandle function instructs your component to retrieve the data that is to be imported from a specified handle. The MovieImportFile function instructs you to retrieve the data from a file. You should set the appropriate flags in your component's componentFlags field to indicate which of these functions your component supports. Note that your component may support both functions.

Before the Movie Toolbox calls one of these functions, a requesting application may call one or more of your component's configuration functions (see "Configuring Movie Data Import Components" for more information about these functions). However, your component should work properly even if none of these configuration functions is called.

MovieImportHandle

The MovieImportHandle function allows the Movie Toolbox to import data from a handle, using your movie data import component.

pascal ComponentResult MovieImportHandle (MovieImportComponent ci,
                                         Handle dataH,
                                         Movie theMovie,
                                         Track targetTrack,
                                         Track *usedTrack,
                                         TimeValue atTime,
                                         TimeValue *addedDuration,
                                          long inFlags,
                                         long *outFlags);
ci
Identifies the Movie Toolbox's connection to your movie data import component.

dataH
Contains a handle to the data that is to be imported into the movie identified by the parameter theMovie . The data contained in this handle has a data type value that corresponds to your component's subtype value.

Your component is not responsible for disposing of this handle.

theMovie
Identifies the movie for this operation. This movie identifier is supplied by the Movie Toolbox. Your component may use this identifier to add sample data to the target movie, or to obtain information about the movie.

targetTrack
Identifies the track that is to receive the imported data. This track identifier is supplied by the Movie Toolbox and is valid only if the movieImportMustUseTrack flag in the inFlags parameter is set to 1.

usedTrack
Contains a pointer to the track that received the imported data. Your component returns this track identifier to the Movie Toolbox. Your component needs to set this parameter only if you operate on a single track or if you create a new track. If you modify more than one track, leave the field referred to by this parameter unchanged.

atTime
Specifies the time corresponding to the location where your component is to place the imported data. This time value is expressed in the movie's time coordinate system.

addedDuration
Contains a pointer to the duration of the data that your component added to the movie. Your component must specify this value in the movie's time coordinate system.

inFlags
Specifies control information governing the import operation. The following flags are defined:

movieImportCreateTrack
Indicates that your component should create a new track to receive the imported data. You must create a track whose type value corresponds to the media type that you have specified in your component's manufacturer code. You should return the track identifier of this new track in the field referred to by the usedTrack parameter, unless you create more than one track. If you create more than one track, be sure to set the movieImportResultUsedMultipleTracks flag (in the field referred to by the outFlags parameter) to 1.

If the movieImportCreateTrack flag is set to 1, then the movieImportMustUseTrack flag is set to 0.

movieImportMustUseTrack
Indicates that your component must use an existing track. That track is identified by the targetTrack parameter. If you create more than one track, be sure to set the movieImportResultUsedMultipleTracks flag (in the field referred to by the outFlags parameter) to 1.

If the movieImportMustUseTrack flag is set to 1, then the movieImportCreateTrack flag is set to 0.

If both the movieImportCreateTrack and movieImportMustUseTrack flags are set to 0, then you are free to use any existing tracks in the movie or to create a new track (or tracks) as needed.

movieImportInParallel
Indicates whether you are to perform an insert operation or a paste operation. If this flag is set to 0, then you should insert the imported data into the target track. If this flag is set to 1, then you should add the imported data to the track, overwriting preexisting open space currently in the track. Note that an application may use the MovieImportSetDuration function (described on [link] ) to control the amount of data you paste into a movie.

If the movieImportMustUseTrack flag is set to 1, then you should use the track specified by the targetTrack parameter. If this is not possible, return an appropriate Movie Toolbox result code.

outFlags
Contains a pointer to a field that is to receive status information about the import operation. Your component sets the appropriate flags in this field when the operation is complete. The following flags are defined:

movieImportResultUsedMultipleTracks
Indicates that your component modified more than one track in the movie. Set this flag to 1 if your component places imported data into more than one track. In this case, you do not need to update the field referred to by the usedTrack parameter.

movieImportInParallel
Indicates whether you performed an insert operation or a paste operation. Set this flag to 0 if you inserted the imported data into the target track. Set this flag to 1 if you added the imported data to the track, overwriting preexisting open space currently in the track.

DESCRIPTION

The Movie Toolbox calls the MovieImportHandle function in order to import movie data from a handle. The data stored in the handle has a data type that corresponds to the component subtype of your movie data import component. Your component must read the data from the supplied handle, perform appropriate conversions on that data, and place the data into the movie.

If your component can accept data from a handle, be sure to set the canMovieImportHandles flag in your component's componentFlags field.

Your component must be prepared to perform this function at any time. You should not expect that any of your component's configuration functions will be called first.

RESULT CODES

invalidTrack

-2009

Specified track cannot receive imported data

Other appropriate Movie Toolbox result codes

SEE ALSO

The Movie Toolbox uses the MovieImportFile function to import data from a file; this function is described next.

MovieImportFile

The MovieImportFile function allows the Movie Toolbox to import data from a file, using your movie data import component.

pascal ComponentResult MovieImportFile (MovieImportComponent ci,
                                          const FSSpec *theFile,
                                          Movie theMovie,
                                          Track targetTrack,
                                          Track *usedTrack,
                                          TimeValue atTime,
                                          TimeValue *addedDuration,
                                          long inFlags,
                                          long *outFlags);
ci
Identifies the Movie Toolbox's connection to your movie data import component.

theFile
Contains a pointer to the file that contains the data that is to be imported into the movie. This file's type value corresponds to your component's subtype value.

theMovie
Identifies the movie for this operation. This movie identifier is supplied by the Movie Toolbox. Your component may use this identifier to add sample data to the target movie or to obtain information about the movie.

targetTrack
Identifies the track that is to receive the imported data. This track identifier is supplied by the Movie Toolbox and is valid only if the movieImportMustUseTrack flag in the inFlags parameter is set to 1.

usedTrack
Contains a pointer to the track that received the imported data. Your component returns this track identifier to the Movie Toolbox. Your component needs to set this parameter only if you operate on a single track or if you create a new track. If you modify more than one track, leave the field referred to by this parameter unchanged.

atTime
Specifies the time corresponding to the location where your component is to place the imported data. This time value is expressed in the movie's time coordinate system.

addedDuration
Contains a pointer to the duration of the data that your component added to the movie. Your component must specify this value in the movie's time coordinate system.

inFlags
Specifies control information governing the import operation. The following flags are defined:

movieImportCreateTrack
Indicates that your component should create a new track to receive the imported data. You must create a track whose type value corresponds to the media type you have specified in your component's manufacturer code. You should return the track identifier of this new track in the field referred to by the usedTrack parameter, unless you create more than one track. If you create more than one track, be sure to set the movieImportResultUsedMultipleTracks flag (in the field referred to by the outFlags parameter) to 1.

If the MovieImportCreateTrack flag is set to 1, then the movieImportMustUseTrack flag is set to 0.

movieImportMustUseTrack
Indicates that your component must use an existing track. That track is identified by the targetTrack parameter. If you create more than one track, be sure to set the movieImportResultUsedMultipleTracks flag (in the field referred to by the outFlags parameter) to 1.

If the movieImportMustUseTrack flag is set to 1, then the movieImportCreateTrack flag is set to 0.

If both the movieImportCreateTrack and movieImportMustUseTrack flags are set to 0, then you are free to use any existing tracks in the movie, or to create a new track (or tracks) as needed.

movieImportInParallel
Indicates whether you are to perform an insert operation or a paste operation. If this flag is set to 0, then you should insert the imported data into the target track. If this flag is set to 1, then you should add the imported data to the track, overwriting the preexisting open space currently in the track. Note that an application may use the MovieImportSetDuration function to control the amount of data you paste into a movie.

If the movieImportMustUseTrack flag is set to 1, then you should use the track specified by the targetTrack parameter. If this is not possible, return an appropriate Movie Toolbox result code.

outFlags
Identifies a field that is to receive status information about the import operation. Your component sets the appropriate flags in this field when the operation is complete. The following flags are defined:

movieImportResultUsedMultipleTracks
Indicates that your component modified more than one track in the movie. Set this flag to 1 if your component places imported data into more than one track. In this case, you do not need to update the field referred to by the usedTrack parameter.

movieImportInParallel
Indicates whether you performed an insert operation or a paste operation. Set this flag to 0 if you inserted the imported data into the target track. Set this flag to 1 if you added the imported data to the track, overwriting preexisting open space currently in the track.

DESCRIPTION

The Movie Toolbox calls the MovieImportFile function in order to import movie data from a file. The file's type corresponds to the component subtype of your movie data import component. Your component must read the data from the supplied file, perform appropriate conversions on that data, and place the data into the movie.

If your component can accept data from a file, be sure to set the canMovieImportFiles flag in your component's componentFlags field.

Your component must be prepared to perform this function at any time. You should not expect that any of your component's configuration functions will be called first.

RESULT CODES

invalidTrack

-2009

Specified track cannot receive imported data

Other appropriate Movie Toolbox result codes

SEE ALSO

The Movie Toolbox uses the MovieImportHandle function to import data from a handle.

© 1997 Apple Computer, Inc.

| Previous | Chapter contents | Chapter top | Section top | Next |